---
title: QR Code
description: Using the QR code machine in your project.
package: "@zag-js/qr-code"
---

QR (Quick Response) Code is used to provide information or link which can be
accessed by scanning the code with an app or a smartphone.

> **Good to know**: The QR code encoding logic is built on top of the
> [`uqr`](https://github.com/unjs/uqr) library.

<Resources pkg="@zag-js/qr-code" />

<Showcase id="QRCode" />

**Features**

- Renders an SVG element (good for SSR)
- Customize the size of the QR code in pixels
- Set the error correction level
- Customize the background and foreground color

## Installation

To use the QR code machine in your project, run the following command in your
command line:

<CodeSnippet id="qr-code/installation.mdx" />

## Anatomy

To set up the QR code correctly, you'll need to understand its anatomy and how
we name its parts.

> Each part includes a `data-part` attribute to help identify them in the DOM.

<Anatomy id="qr-code" />

## Usage

First, import the QR code package into your project

```jsx
import * as qrCode from "@zag-js/qr-code"
```

The QR code package exports two key functions:

- `machine` — The state machine logic for the QR code widget.
- `connect` — The function that translates the machine's state to JSX attributes
  and event handlers.

Next, import the required hooks and functions for your framework and use the QR
code machine in your project 🔥

<CodeSnippet id="qr-code/usage.mdx" />

## Setting the QR Code value

To set the value of the QR code, pass the `value` property to the machine.

```jsx {3}
const service = useMachine(qrCode.machine, {
  // ...
  value: "https://example.com",
})
```

### Setting the correction level

Error correction allows for the QR code to be blocked or resized while still
recognizable. In some cases where the link is too long or the logo overlay
covers a significant area, the error correction level can be increased.

The QR code machine accepts the following error correction levels:

- `L`: Allows recovery of up to 7% data loss (default)
- `M`: Allows recovery of up to 15% data loss
- `Q`: Allows recovery of up to 25% data loss
- `H`: Allows recovery of up to 30% data loss

To set the error correction level, pass the `encoding.ecc` or
`encoding.boostEcc` context property.

```jsx {3}
const service = useMachine(qrCode.machine, {
  value: "...",
  encoding: { ecc: "H" },
})
```

> The alternative is to enlarge the QRCode by increasing the size of the `svg`
> element.

### Adding an overlay logo

To add a logo overlay to the QR code, render the image part. The logo will be
automatically centered within the QR code.

```jsx {3}
<div {...api.getRootProps()}>
  <svg {...api.getFrameProps()}>{/** ... */}</svg>
  <div {...api.getOverlayProps()}>
    <img src="..." alt="" />
  </div>
</div>
```

### Changing the color

To change the color of the QR code, set the `fill` attribute on the `path` part.

```css
[data-scope="qr-code"][data-part="pattern"] {
  fill: green;
}
```

To change the background color of the QR code, set the `background-color`

```css
[data-scope="qr-code"][data-part="frame"] {
  background-color: white;
}
```

### Exporting the QR code

To export the QR code as an image, you can use the `api.getDataURL` method.

```ts
api.getDataURL({ type: "image/png" }).then((url) => {
  // do something with the URL (like download it)
})
```

## Styling guide

Earlier, we mentioned that each QR code part has a `data-part` attribute added
to them to select and style them in the DOM.

```css
[data-scope="qr-code"][data-part="root"] {
  /* Styles for the root part */
}

[data-scope="qr-code"][data-part="frame"] {
  /* Styles for the svg part */
}

[data-scope="qr-code"][data-part="pattern"] {
  /* Styles for the path */
}

[data-scope="qr-code"][data-part="overlay"] {
  /* Styles for the logo */
}
```

## Methods and Properties

### Machine Context

The QR code machine exposes the following context properties:

<ContextTable name="qr-code" />

### Machine API

The QR code `api` exposes the following methods:

<ApiTable name="qr-code" />
